OpenAI Harness
正文
尽可能根据原文和我的笔记整理出构建Agents-first Repo的pipeline和需要注意的事项、需要遵守的黄金准则、需要做的准备....
几个核心原则
- no manually-written code.
- Humans steer, Agents execute
- Enabling the agents to do useful work(offer tools for agents)
- 遇到问题先问:"what capability is missing, and how do we make it both legible and enforceable for the agent?"
- give Codex a map, not a 1,000-page instruction manual.(下面有可以参考的目录结构和设计，在这里插入链接)
- Our most difficult challenges now center on designing environments, feedback loops, and control systems that help agents accomplish our goal: build and maintain complex, reliable software at scale.
Humans steer, Agents execute
为什么刻意禁止人类手写代码
团队主动规定“所有代码都由 Codex 编写”，并不是因为人工编码不好，而是为了避免人类在 Agent 遇到问题时直接接管。 否则典型流程会变成：
Agent 做不好
→ 人类亲自修复
→ 问题暂时解决
→ Agent 的能力和环境没有改善
在这个约束下，人类只能寻找系统性原因：
- Agent 是否缺少工具？
- 文档是否不完整？
- 测试反馈是否不充分？
- 架构是否难以理解？
- 任务描述是否不够明确？ 然后通过改善环境来解决问题。这样一次改进可以作用于之后的所有任务，而不是只解决当前一个 Bug。
即出现问题优先优化Agent(工具，文档，测试，架构，任务描述)， 而不是手动修改代码bug
4. 工程师的主要工作发生了变化
三个新职责。
设计环境
让 Agent 能直接访问：
- 代码仓库；
- 测试系统；
- 应用界面；
- 日志、指标和 Trace；
- GitHub 和 CI 工具。
Agent 不能访问的内容，实际上就无法稳定利用。
表达意图
人类需要说明的不只是“写什么代码”，而是：
- 目标是什么；
- 哪些条件必须满足；
- 哪些约束不能违反；
- 如何判断任务已经完成。
例如，相比“优化启动代码”，更好的表达是：
服务启动时间必须低于 800 毫秒，并通过性能测试验证。
建立反馈回路
Agent 必须能观察自己工作的后果：
执行
→ 获取真实结果
→ 判断是否满足目标
→ 修正
→ 再次验证
没有反馈回路，Agent 只是一次性生成代码；有了反馈回路，它才更接近一个能够自主工作的工程主体。
5. 最稀缺的资源是人类注意力
代码生成能力提高后，新的瓶颈会变成人类：
- 人类没有时间审查每一行代码；
- 无法手动验证每个界面；
- 无法持续回答 Agent 的所有问题；
- 无法逐个处理高频 PR。
所以系统设计的目标不是单纯“让 Agent 多写代码”，而是：
尽量减少每项任务所消耗的人类判断和注意力。
人类只介入机器难以承担的部分，例如需求优先级、产品取舍、安全边界和最终责任。
Increasing application legibility
add more capabilities to the agent by making things like the application UI, logs, and app metrics themselves directly legible to Codex. 提供observability tooling. Logs, metrics, and traces are exposed to Codex
made repository knowledge the system of record
When everything is “important,” nothing is.
give Codex a map, not a 1,000-page instruction manual.
instead of treating AGENTS.md as the encyclopedia, we treat it as the table of contents.
可以参考的设计和目录结构
The repository’s knowledge base lives in a structured docs/ directory treated as the system of record.
AGENTS.md
ARCHITECTURE.md
docs/
├── design-docs/
│ ├── index.md
│ ├── core-beliefs.md
│ └── ...
├── exec-plans/
│ ├── active/
│ ├── completed/
│ └── tech-debt-tracker.md
├── generated/
│ └── db-schema.md
├── product-specs/
│ ├── index.md
│ ├── new-user-onboarding.md
│ └── ...
├── references/
│ ├── design-system-reference-llms.txt
│ ├── nixpacks-llms.txt
│ ├── uv-llms.txt
│ └── ...
├── DESIGN.md
├── FRONTEND.md
├── PLANS.md
├── PRODUCT_SENSE.md
├── QUALITY_SCORE.md
├── RELIABILITY.md
└── SECURITY.md
Agent legibility is the goal
Agent-first 项目中，仓库本身就是 Agent 的知识边界。凡是希望 Agent 稳定遵守和利用的信息，都应尽量转化为仓库内可搜索、可版本化、可验证的产物。 如果一个规则很重要，就不应该只存在于飞书或者微信中，而应该加入到仓库里面
Entropy and garbage collection
Encode “golden principles” directly into the repository and built a recurring cleanup process. Golden principles example: (1) we prefer shared utility packages over hand-rolled helpers to keep invariants centralized, and (2) we don’t probe data “YOLO-style”—we validate boundaries or rely on typed SDKs so the agent can’t accidentally build on guessed shapes
具体实现
一、Golden principles 的三层实现
1. 文档层：告诉 Agent 原则是什么
不要全部塞进 AGENTS.md。AGENTS.md 应该只是入口和地图：
AGENTS.md
ARCHITECTURE.md
docs/
├── engineering/
│ └── golden-principles.md
├── quality/
│ ├── quality-score.md
│ └── tech-debt.md
└── domains/
AGENTS.md 可以这样写：
## Code quality
Before modifying production code, read:
- docs/engineering/golden-principles.md
- ARCHITECTURE.md
详细解释、正反例和修复方式放进 golden-principles.md。
文章本身也强调：AGENTS.md 应该是目录，而不是巨型百科全书。
机械约束层：把原则变成工具
仅有文档不够。能自动检查的原则应写成：
- ESLint/custom lint；
- dependency graph 检查；
- AST 扫描；
- 类型检查；
- 结构测试；
- 单元测试；
- CI 规则。
即使用传统软件工程本身就有的静态检查
治理层：定期 Agent 自动清理
可以设置定时任务，例如每天或每周：
定时触发
→ Agent 读取 golden principles
→ 扫描代码库
→ 运行 lint / quality scripts
→ 找出一类问题
→ 创建小型重构 PR
→ CI 验证
→ 人工或 Agent review
→ 满足条件后合并
文章描述的就是这种模式：后台 Codex 任务定期扫描偏差、更新质量评分，并创建针对性的重构 PR；很多 PR 很小，可以快速评审甚至自动合并。